Crate der_derive Copy item path

§RustCrypto: DER Custom Derive Support

Custom derive support for the der crate’s Choice and Sequence traits:

https://github.com/RustCrypto/formats/tree/master/der

Documentation

§Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

§License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§About

Custom derive support for the der crate.

This crate contains custom derive macros intended to be used in the following way:

• Choice: map ASN.1 CHOICE to a Rust enum.
• Enumerated: map ASN.1 ENUMERATED to a C-like Rust enum.
• Sequence: map ASN.1 SEQUENCE to a Rust struct.
• ValueOrd: determine DER ordering for ASN.1 SET OF.

Note that this crate shouldn’t be used directly, but instead accessed by using the derive feature of the der crate, which re-exports the above macros from the toplevel.

§Why not serde?

The der crate is designed to be easily usable in embedded environments, including ones where code size comes at a premium.

This crate (i.e. der_derive) is able to generate code which is significantly smaller than serde_derive. This is because the der crate has been designed with high-level abstractions which reduce code size, including trait object-based encoders which allow encoding logic which is duplicated in serde serializers to be implemented in a single place in the der crate.

This is a deliberate tradeoff in terms of performance, flexibility, and code size. At least for now, the der crate is optimizing for leveraging as many abstractions as it can to minimize code size.

§Toplevel attributes

The following attributes can be added to an enum or struct when deriving either Choice or Sequence respectively:

§#[asn1(tag_mode = "...")] attribute: EXPLICIT vs IMPLICIT

This attribute can be used to declare the tagging mode used by a particular ASN.1 module.

It’s used when parsing CONTEXT-SENSITIVE fields.

The default is EXPLICIT, so the attribute only needs to be added when a particular module is declared IMPLICIT.

§#[asn1(error = ...)] attribute: custom error types for decoding

By default generated Decode / DecodeValue implementations generated by macros from this crate use der::Error as the generic Error parameter, but it’s possible to use a custom error type that implements From<der::Error> by using this attribute.

Note that Choice puts more restrictions on the error type: during decoding for each enum variant the type in its #[asn1(type = "...")] attribute (let’s call it T) is constructed and then converted to the actual variant’s type (this one will be U) using the TryInto trait. That means that for each enum variant’s type U the custom error type must implement From<<U as TryFrom<T>>::Error>. Since U and T types are usually the same implementing From<Infallible> should do it.

§Field-level attributes

The following attributes can be added to either the fields of a particular struct or the variants of a particular enum:

§#[asn1(context_specific = "...")] attribute: CONTEXT-SPECIFIC support

This attribute can be added to associate a particular CONTEXT-SPECIFIC tag number with a given enum variant or struct field.

The value must be quoted and contain a number, e.g. #[asn1(context_specific = "29")].

§#[asn1(default = "...")] attribute: DEFAULT support

This behaves like serde_derive’s default attribute, allowing you to specify the path to a function which returns a default value.

§#[asn1(extensible = "true")] attribute: support for ... extensibility operator

This attribute can be applied to the fields of struct types, and will skip over unrecognized lower-numbered CONTEXT-SPECIFIC fields when looking for a particular field of a struct.

§#[asn1(optional = "true")] attribute: support for OPTIONAL fields

This attribute explicitly annotates a field as OPTIONAL.

§#[asn1(type = "...")] attribute: ASN.1 type declaration

This attribute can be used to specify the ASN.1 type for a particular enum variant or struct field.

It’s presently mandatory for all enum variants, even when using one of the ASN.1 types defined by this crate.

For structs, placing this attribute on a field makes it possible to decode/encode types which don’t directly implement the Decode/Encode traits but do impl From and TryInto and From for one of the ASN.1 types listed below (use the ASN.1 type keywords as the type):

• BIT STRING: performs an intermediate conversion to der::asn1::BitString
• IA5String: performs an intermediate conversion to der::asn1::IA5String
• GeneralizedTime: performs an intermediate conversion to der::asn1::GeneralizedTime
• OCTET STRING: performs an intermediate conversion to der::asn1::OctetString
• PrintableString: performs an intermediate conversion to der::asn1::PrintableString
• UTCTime: performs an intermediate conversion to der::asn1::UtcTime
• UTF8String: performs an intermediate conversion to der::asn1::Utf8String

§#[asn1(constructed = "...")] attribute: support for constructed inner types

This attribute can be used to specify that an “inner” type is constructed. It is most commonly used when a CHOICE has a constructed inner type.

Note: please open a GitHub Issue if you would like to request support for additional ASN.1 types.

§#[asn1(tag_mode = "...")] attribute: EXPLICIT vs IMPLICIT

This attribute can be used to declare the tagging mode used for a field of a struct which derives Sequence or for a variant of an enum which derives Choice. It allows to override the toplevel tag_mode attribute, for the fields and variants that specify it.